home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 400_01 / socketpp-1.5 / socket++.info-1 < prev    next >
Encoding:
GNU Info File  |  1993-11-06  |  48.0 KB  |  1,412 lines
  1. This is Info file socket++.info, produced by Makeinfo-1.49 from the
  2. input file socket++.texi.
  3.  
  4.    This info file describes the C++ family of socket classes.
  5.  
  6.    Copyright (C) 1992,1993 Gnanasekaran Swaminathan <gs4t@virginia.edu>
  7.  
  8.    Permission is granted to make and distribute verbatim copies of this
  9. document provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.  
  12. 
  13. File: socket++.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)
  14.  
  15. Socket++ Library
  16. ****************
  17.  
  18.    Socket++ is a family of C++ classes that gives the same interface as
  19. the iostream classes for input and output for communication between
  20. processes.
  21.  
  22.    This documentation describes Version: 07Nov93 1.5 of socket++
  23. library.
  24.  
  25. * Menu:
  26.  
  27. * Copying::                     Copyright information.
  28. * Acknowledgments::             Thanks!
  29. * Overview of Socket++::        Overview of socket++ library.
  30. * sockbuf Class::               Socket streambuf class.
  31. * sockAddr Class::              Base class for socket addresses.
  32.  
  33. * sockinetbuf Class::           Socket class for INET address family.
  34. * sockinetaddr Class::          Address class for INET address family of
  35.                                         sockets.
  36.  
  37. * sockunixbuf Class::           Socket class for UNIX address family.
  38. * sockunixaddr Class::          Address class for UNIX address family of
  39.                                         sockets.
  40.  
  41. * sockstream Classes::          I/O socket stream classes and some examples.
  42. * pipestream Classes::          I/O stream classes that provides pipe,
  43.                                         socketpair, and popen facilities.
  44.  
  45. * Error Handling::              Describes the default error handling in
  46.                                         the socket++ library.
  47. * Pitfalls::                    Common mistakes that socket++ library
  48.                                         users make.
  49.  
  50. * Index::                       Index to concepts and program names
  51.  
  52. 
  53. File: socket++.info,  Node: Copying,  Next: Acknowledgments,  Prev: Top,  Up: Top
  54.  
  55. Socket++ Library Copyright Notice
  56. *********************************
  57.  
  58.    Copyright (C) 1992,1993 Gnanasekaran Swaminathan
  59.  
  60.    Permission is granted to use at your own risk and distribute this
  61. software in source and binary forms provided the above copyright notice
  62. and this paragraph are preserved on all copies. This software is
  63. provided "as is" with no express or implied warranty.
  64.  
  65. 
  66. File: socket++.info,  Node: Acknowledgments,  Next: Overview of Socket++,  Prev: Copying,  Up: Top
  67.  
  68. Acknowledgments
  69. ***************
  70.  
  71.    Gordon Joly <G.Joly@cs.ucl.ac.uk> for reporting bugs in pipestream
  72. class implementation and providing an ftp site for the socket++ library
  73. at     cs.ucl.ac.uk:~ftp/coside/gnu/socket++-1.x.tar.gz He also knows how
  74. to make the socket++ library a shared library.
  75.  
  76.    Jim Anderson for reporting a bug in sockinet.C
  77.  
  78.    Carl Gay <cgay@skinner.cs.uoregon.edu> for reporting a bug and a fix
  79. in sockinet.C
  80.  
  81.    Oliver Imbusch <flabes@parystec.de> for reporting a bug in
  82. Makefile.in and suggesting several enhancements for sockbuf class.
  83.  
  84.    Per Bothner <bothner@cygnus.com> for configure, config.sub,
  85. config.shared and move-if-change files that are used to generate
  86. Makefile. These files are taken from his libg++-2.4 and hence, these
  87. files are governed by the Copyright Notice found in the file LICENCE in
  88. libg++.
  89.  
  90. 
  91. File: socket++.info,  Node: Overview of Socket++,  Next: sockbuf Class,  Prev: Acknowledgments,  Up: Top
  92.  
  93. Overview of Socket++ Library
  94. ****************************
  95.  
  96.    Socket++ library defines a family of C++ classes that can be used
  97. more effectively than directly calling the underlying low-level system
  98. functions. One distinct advantage of the socket++ is that it has the
  99. same interface as that of the iostream so that the users can perform
  100. type-safe input output. *Note IOStream: (libg++)IOStream, for more
  101. information on iostream library.
  102.  
  103.    `streambuf' counterpart of the socket++ is `sockbuf'. `sockbuf' is
  104. an endpoint for communication with yet another `sockbuf' or simply a
  105. `socket' descriptor. `sockbuf' has also methods that act as interfaces
  106. for most of the commonly used system calls that involve sockets. *Note
  107. sockbuf Class::, for more information on the socket buffer class.
  108.  
  109.    For each communication domain, we derive a new class from `sockbuf'
  110. that has some additional methods that are specific to that domain. At
  111. present, only UNIX and INET domains are supported. `sockunixbuf' class
  112. and `sockinetbuf' class define the UNIX and INET domain of sockets
  113. respectively. *Note sockunixbuf Class::, for UNIX sockets and *Note
  114. sockinetbuf Class::, for INET sockets.
  115.  
  116.    We also have domain specific socket address classes that are derived
  117. from a common base class called `sockAddr'. `sockunixaddr' class is
  118. used for UNIX domain addresses and `sockinetaddr' class is used for
  119. INET domain addresses. For more information on address classes see
  120. *Note sockAddr Class::, *Note sockunixaddr Class::, and *Note
  121. sockinetaddr Class::.
  122.      *Note*: `sockAddr' is not spelled `sockaddr' in order to prevent
  123.      name clash with the `struct sockaddr' declared in `<sys/socket.h>'.
  124.  
  125.    We noted earlier that socket++ provides the same interface as the
  126. iostream library. For example, in the internet domain, we have
  127. `isockinet', `osockinet', and `iosockinet' classes that are
  128. counterparts to `istream', `ostream', and `iostream' classes of `libg++
  129. iostream' library. For more details on `iosockstream' classes see *Note
  130. sockstream Classes::.
  131.  
  132.    The services of `pipe()', `socketpair()', and `popen()' are provided
  133. by the `pipestream' class. *Note pipestream Classes::.
  134.  
  135. 
  136. File: socket++.info,  Node: sockbuf Class,  Next: sockAddr Class,  Prev: Overview of Socket++,  Up: Top
  137.  
  138. `sockbuf' Class
  139. ***************
  140.  
  141.    `sockbuf' class is derived from `streambuf' class of the libg++
  142. iostream library. You can simultaneously read and write into a
  143. `sockbuf' just like you can listen and talk through a telephone. To
  144. accomplish the above goal, we maintain two independent buffers for
  145. reading and writing.
  146.  
  147. * Menu:
  148.  
  149. * Constructors::              How to construct a `sockbuf' object
  150.                                      and how to open a socket?
  151. * Destructor::                How to destruct a `sockbuf' object
  152.                                      and how to close a socket?
  153. * Reading and Writing::       How to use `sockbuf' as `streambuf'?
  154. * Connection Establishment::  How to bind an address and establish a
  155.                                      connection?
  156. * Socket Options::            How to set and get socket options?
  157. * Timeouts::                  How to gracefully handle connection inactivity?
  158.  
  159. 
  160. File: socket++.info,  Node: Constructors,  Next: Destructor,  Up: sockbuf Class
  161.  
  162. Constructors
  163. ============
  164.  
  165.    `sockbuf' constructors sets up an endpoint for communication. A
  166. `sockbuf' object so created can be read from and written to in
  167. linebuffered mode. To change mode, refer to `streambuf' class in *Note
  168. IOStream: (libg++)IOStream.
  169.  
  170.    `sockbuf' objects are created as follows where
  171.    - `s' and `so' are `sockbuf' objects
  172.  
  173.    - `sd' is an integer which is a socket descriptor
  174.  
  175.    - `af' and `proto' are integers which denote domain number and
  176.      protocol number respectively
  177.  
  178.    - `ty' is a `sockbuf::type' and must be one of
  179.      `sockbuf::sock_stream', `sockbuf::sock_dgram',
  180.      `sockbuf::sock_raw', `sockbuf::sock_rdm', and
  181.      `sockbuf::sock_seqpacket'
  182.  
  183. `sockbuf s(sd);'
  184. `sockbuf s;'
  185.      Set socket descriptor of `s' to `sd' (defaults to -1). `sockbuf'
  186.      destructor will close `sd'.
  187.  
  188. `sockbuf s(af, ty, proto);'
  189.      Set socket descriptor of `s' to `::socket(af, int(ty), proto);'
  190.  
  191. `sockbuf so(s);'
  192.      Set socket descriptor of `so' to the socket descriptor of `s'.
  193.  
  194. `s.open(ty, proto)'
  195.      does nothing and returns simply `0', the null pointer to `sockbuf'.
  196.  
  197. `s.is_open()'
  198.      returns a non-zero number if the socket descriptor is open else
  199.      return 0.
  200.  
  201. `s = so;'
  202.      return a reference `s' after assigning `s' with `so'.
  203.  
  204. 
  205. File: socket++.info,  Node: Destructor,  Next: Reading and Writing,  Prev: Constructors,  Up: sockbuf Class
  206.  
  207. Destructor
  208. ==========
  209.  
  210.    `sockbuf::~sockbuf()' flushes output and closes its socket if no
  211. other sockbuf is referencing it and _S_DELETE_DONT_CLOSE flag bit of
  212. `streambuf' base class is not set. It also deletes its read and write
  213. buffers.
  214.  
  215.    In what follows,
  216.    - `s' is a `sockbuf' object
  217.  
  218.    - `how' is of type `sockbuf::shuthow' and must be one of
  219.      `sockbuf::shut_read', `sockbuf::shut_write', and
  220.      `sockbuf::shut_readwrite'
  221.  
  222. `sockbuf::~sockbuf()'
  223.      flushes output and closes its socket if no other `sockbuf' object
  224.      is referencing it before deleting its read and write buffers. If
  225.      the _S_DELETE_DONT_CLOSE bit of `streambuf' base class is set,
  226.      then the socket is not closed.
  227.  
  228. `s.close()'
  229.      closes the socket even if it is referenced by other `sockbuf'
  230.      objects and _S_DELETE_DONT_CLOSE flag is set.
  231.  
  232. `s.shutdown(how)'
  233.      shuts down read if `how' is `sockbuf::shut_read', shuts down write
  234.      if `how' is `sockbuf::shut_write', and shuts down both read and
  235.      write if `how' is `sockbuf::shut_readwrite'.
  236.  
  237. 
  238. File: socket++.info,  Node: Reading and Writing,  Next: Connection Establishment,  Prev: Destructor,  Up: sockbuf Class
  239.  
  240. Reading and Writing
  241. ===================
  242.  
  243.    `sockbuf' class offers several ways to read and write and tailors
  244. the behavior of several virtual functions of `streambuf' for socket
  245. communication.
  246.  
  247.    In case of error, `sockbuf::error(const char*)' is called.
  248.  
  249.    In what follows,
  250.    - `s' is a `sockbuf' object
  251.  
  252.    - `buf' is buffer of type `char*'
  253.  
  254.    - `bufsz' is an integer and is less than `sizeof(buf)'
  255.  
  256.    - `msgf' is an integer and denotes the message flag
  257.  
  258.    - `sa' is of type `sockAddr'
  259.  
  260.    - `msgh' is a pointer to `struct msghdr'
  261.  
  262.    - `wp' is an integer and denotes time in seconds
  263.  
  264.    - `c' is a char
  265.  
  266. `s.is_open()'
  267.      returns a non-zero number if the socket descriptor is open else
  268.      return 0.
  269.  
  270. `s.is_eof()'
  271.      returns a non-zero number if the socket has seen EOF while reading
  272.      else return 0.
  273.  
  274. `s.write(buf, bufsz)'
  275.      returns an int which must be equal to `bufsz' if `bufsz' chars in
  276.      the `buf' are written successfully. It returns 0 if there is
  277.      nothing to write or if, in case of timeouts, the socket is not
  278.      ready for write *Note Timeouts::.
  279.  
  280. `s.send(buf, bufsz, msgf)'
  281.      same as `sockbuf::write' described above but allows the user to
  282.      control the transmission of messages using the message flag `msgf'.
  283.      If `msgf' is `sockbuf::msg_oob' and the socket type of `s' is
  284.      `sockbuf::sock_stream', `s' sends the message in OUT-OF-BAND mode.
  285.      If `msgf' is `sockbuf::msg_dontroute', `s' sends the outgoing
  286.      packets without routing. If `msgf' is 0, which is the default
  287.      case, `sockbuf::send' behaves exactly like `sockbuf::write'.
  288.  
  289. `s.sendto(sa, buf, bufsz, msgf)'
  290.      same as `sockbuf::send' but works on unconnected sockets. `sa'
  291.      specifies the TO address for the message.
  292.  
  293. `s.sendmsg(msgh, msgf)'
  294.      same as `sockbuf::send' but sends a `struct msghdr' object instead.
  295.  
  296. `s.sys_write(buf, bufsz)'
  297.      calls `sockbuf::write' and returns the result. Unlike
  298.      `sockbuf::write' `sockbuf::sys_write' is declared as a virtual
  299.      function.
  300.  
  301. `s.read(buf, bufsz)'
  302.      returns an int which is the number of chars read into the `buf'. In
  303.      case of EOF, return EOF. Here, `bufsz' indicates the size of the
  304.      `buf'. In case of timeouts, return 0 *Note Timeouts::.
  305.  
  306. `s.recv(buf, bufsz, msgf)'
  307.      same as `sockbuf::read' described above but allows the user to
  308.      receive OUT-OF-BAND data if `msgf' is `sockbuf::msg_oob' or to
  309.      preview the data waiting to be read if `msgf' is
  310.      `sockbuf::msg_peek'. If `msgf' is 0, which is the default case,
  311.      `sockbuf::recv' behaves exactly like `sockbuf::read'.
  312.  
  313. `s.recvfrom(sa, buf, bufsz, msgf)'
  314.      same as `sockbuf::recv' but works on unconnected sockets. `sa'
  315.      specifies the FROM address for the message.
  316.  
  317. `s.recvmsg(msgh, msgf)'
  318.      same as `sockbuf::recv' but reads a `struct msghdr' object instead.
  319.  
  320. `s.sys_read(buf, bufsz)'
  321.      calls `sockbuf::read' and returns the result. Unlike
  322.      `sockbuf::read' `sockbuf::sys_read' is declared as a virtual
  323.      function.
  324.  
  325. `s.is_readready(wp_sec, wp_usec)'
  326.      returns a non-zero int if `s' has data waiting to be read from the
  327.      communication channel. If `wp_sec >= 0', it waits for `wp_sec 10^6
  328.      + wp_usec' microseconds before returning 0 in case there are no
  329.      data waiting to be read. If `wp_sec < 0', then it waits until a
  330.      datum arrives at the communication channel. `wp_usec' defaults to
  331.      0.
  332.           *Please Note*: The data waiting in `sockbuf''s own buffer is
  333.           different from the data waiting in the communication channel.
  334.  
  335. `s.is_writeready(wp_sec, wp_usec)'
  336.      returns a non-zero int if data can be written onto the
  337.      communication channel of `s'. If `wp_sec >= 0', it waits for
  338.      `wp_sec 10^6 + wp_usec' microseconds before returning 0 in case no
  339.      data can be written. If `wp_sec < 0', then it waits until the
  340.      communication channel is ready to accept data. `wp_usec' defaults
  341.      to 0.
  342.           *Please Note*: The buffer of the `sockbuf' class is different
  343.           from the buffer of the communication channel buffer.
  344.  
  345. `s.is_exceptionpending(wp_sec, wp_usec)'
  346.      returns non-zero int if `s' has any exception events pending. If
  347.      `wp_sec >= 0', it waits for `wp_sec 10^6 + wp_usec' microseconds
  348.      before returning 0 in case `s' does not have any exception events
  349.      pending. If `wp_sec < 0', then it waits until an expception event
  350.      occurs. `wp_usec' defaults to 0.
  351.           *Please Note*: The exceptions that
  352.           `sockbuf::is_exceptionpending' is looking for are different
  353.           from the C++ exceptions.
  354.  
  355. `s.flush_output()'
  356.      flushes the output buffer and returns the number of chars flushed.
  357.      In case of error, return EOF. `sockbuf::flush_output' is a
  358.      protected member function and it is not available for general
  359.      public.
  360.  
  361. `s.doallocate()'
  362.      allocates free store for read and write buffers of `s' and returns
  363.      1 if allocation is done and returns 0 if there is no need.
  364.      `sockbuf::doallocate' is a protected virtual member function and it
  365.      is not available for general public.
  366.  
  367. `s.underflow()'
  368.      returns the unread char in the buffer as an unsigned char if there
  369.      is any. Else returns EOF if `s' cannot allocate space for the
  370.      buffers, cannot read or peer is closed. `sockbuf::underflow' is a
  371.      protected virtual member function and it is not available for
  372.      general public.
  373.  
  374. `s.overflow(c)'
  375.      if `c=EOF', call and return the result of `flush_output()', else
  376.      if `c='\n'' and `s' is linebuffered, call `flush_output()' and
  377.      return `c' unless `flush_output()' returns EOF, in which case
  378.      return EOF. In any other case, insert char `c' into the buffer and
  379.      return `c' as an unsigned char. `sockbuf::overflow' is a protected
  380.      member virtual function and it is not available for general public.
  381.  
  382. `s.sync()'
  383.      calls `flush_output()' and returns the result. Useful if the user
  384.      needs to flush the output without writing newline char into the
  385.      write buffer.
  386.  
  387. `s.xsputn(buf, bufsz)'
  388.      write `bufsz' chars into the buffer and returns the number of chars
  389.      successfully written. Output is flushed if any char in
  390.      `buf[0..bufsz-1]' is `'\n''.
  391.  
  392. `s.recvtimeout(wp)'
  393.      sets the recv timeout to `wp' seconds. If `wp' is -1, it is a
  394.      block and if `wp' is 0, it is a poll.
  395.  
  396.      It affects all read functions. If the socket is not read ready
  397.      within `wp' seconds, the read call will return 0. It also affects
  398.      `sockbuf::underflow'. `sockbuf::underflow' will not set the
  399.      `_S_EOF_SEEN' flag if it is returning EOF because of timeout.
  400.  
  401.      `sockbuf::recvtimeout' returns the old recv timeout value.
  402.  
  403. `s.sendtimeout(wp)'
  404.      sets the send timeout to `wp' seconds. If `wp' is -1, it is a
  405.      block and if `wp' is 0, it is a poll.
  406.  
  407.      It affects all write functions. If the socket is not write ready
  408.      within `wp' seconds, the write call will return 0.
  409.  
  410.      `sockbuf::sendtimeout' returns the old send timeout value.
  411.  
  412. 
  413. File: socket++.info,  Node: Connection Establishment,  Next: Socket Options,  Prev: Reading and Writing,  Up: sockbuf Class
  414.  
  415. Establishing connections
  416. ========================
  417.  
  418.    A name must be bound to a `sockbuf' if processes want to refer to it
  419. and use it for communication. Names must be unique. A UNIX name is a
  420. 3-tuple, <PROTOCOL, LOCAL PATH, PEER PATH>. An INET name is a 5-tuple,
  421. <PROTOCOL, LOCAL ADDR, LOCAL PORT, PEER ADDR, PEER PORT>.
  422. `sockbuf::bind' is used to specify the local half of the name--<LOCAL
  423. PATH> for UNIX and <LOCAL ADDR, LOCAL PORT> for INET.
  424. `sockbuf::connect' and `sockbuf::accept' are used to specify the peer
  425. half of the name--<PEER PATH> for UNIX and <PEER ADDR, PEER PORT> for
  426. INET.
  427.  
  428.    In what follows,
  429.    - `s' and `so' are `sockbuf' objects
  430.  
  431.    - `sa' is a `sockAddr' object
  432.  
  433.    - `nc' is an integer denoting the number of connections to allow
  434.  
  435. `s.bind(sa)'
  436.      binds `sockAddr' `sa' as the local half of the name for `s'.
  437.  
  438. `s.connect(sa)'
  439.      `sockbuf::connect' uses `sa' to provide the peer half of the name
  440.      for `s' and to establish the connection itself. `sockbuf::connect'
  441.      also provides the local half of the name automatically and hence,
  442.      the user should not use `sockbuf::bind' to bind any local half of
  443.      the name.
  444.  
  445. `s.listen(nc)'
  446.      makes `s' ready to accept connections. `nc' specifies the maximum
  447.      number of outstanding connections that may be queued and must be
  448.      at least 1 and less than or equal to `sockbuf::somaxconn' which is
  449.      usually 5 on most systems.
  450.  
  451. `sockbuf so = s.accept(sa)'
  452. `sockbuf so = s.accept()'
  453.      accepts connections and returns the peer address in `sa'. `s' must
  454.      be a listening `sockbuf'. See `sockbuf::listen' above.
  455.  
  456. 
  457. File: socket++.info,  Node: Socket Options,  Next: Timeouts,  Prev: Connection Establishment,  Up: sockbuf Class
  458.  
  459. Getting and Setting Socket Options
  460. ==================================
  461.  
  462.    Socket options are used to control a socket communication. New
  463. options can be set and old value of the options can be retrived at the
  464. protocol level or at the socket level by using `setopt' and `getopt'
  465. member functions. In addition, you can also use special member
  466. functions to get and set specific options.
  467.  
  468.    In what follows,
  469.    - `s' is a `sockbuf' object
  470.  
  471.    - `opval' is an integer and denotes the option value
  472.  
  473.    - `op' is of type `sockbuf::option' and must be one of
  474.         * `sockbuf::so_error' used to retrieve and clear error status
  475.  
  476.         * `sockbuf::so_type' used to retrieve type of the socket
  477.  
  478.         * `sockbuf::so_debug' is used to specify recording of debugging
  479.           information
  480.  
  481.         * `sockbuf::so_reuseaddr' is used to specify the reuse of local
  482.           address
  483.  
  484.         * `sockbuf::so_keepalive' is used to specify whether to keep
  485.           connections alive or not
  486.  
  487.         * `sockbuf::so_dontroute' is used to specify whether to route
  488.           messages or not
  489.  
  490.         * `sockbuf::so_broadcast' is used to specify whether to
  491.           broadcast `sockbuf::sock_dgram' messages or not
  492.  
  493.         * `sockbuf::so_oobinline' is used to specify whether to inline
  494.           OUT-OF-BAND data or not.
  495.  
  496.         * `sockbuf::so_linger' is used to specify for how long to
  497.           linger before shutting down
  498.  
  499.         * `sockbuf::so_sndbuf' is used to retrieve and to set the size
  500.           of the send buffer (communication channel buffer not
  501.           `sockbuf''s internal buffer)
  502.  
  503.         * `sockbuf::so_rcvbuf' is used to retrieve and to set the size
  504.           of the recv buffer (communication channel buffer not
  505.           `sockbuf''s internal buffer)
  506.  
  507. `s.getopt(op, &opval, sizeof(opval), oplevel)'
  508.      gets the option value of the `sockbuf::option' `op'  at the option
  509.      level `oplevel' in `opval'. It returns the actual size of the
  510.      buffer `opval' used. The default value of the `oplevel' is
  511.      `sockbuf::sol_socket'.
  512.  
  513. `s.setopt(op, &opval, sizeof(opval), oplevel)'
  514.      sets the option value of the `sockbuf::option' `op'  at the option
  515.      level `oplevel' to `opval'. The default value of the `oplevel' is
  516.      `sockbuf::sol_socket'.
  517.  
  518. `s.gettype()'
  519.      gets the socket type of `s'. The return type is `sockbuf::type'.
  520.  
  521. `s.clearerror()'
  522.      gets and clears the error status of the socket.
  523.  
  524. `s.debug(opval)'
  525.      if `opval' is not -1, set the `sockbuf::so_debug' option value to
  526.      `opval'. In any case, return the old option value of
  527.      `sockbuf::so_debug' option. The default value of `opval' is -1.
  528.  
  529. `s.reuseaddr(opval)'
  530.      if `opval' is not -1, set the `sockbuf::so_reuseaddr' option value
  531.      to `opval'. In any case, return the old option value of
  532.      `sockbuf::so_reuseaddr' option. The default value of `opval' is -1.
  533.  
  534. `s.dontroute(opval)'
  535.      if `opval' is not -1, set the `sockbuf::so_dontroute' option value
  536.      to `opval'. In any case, return the old option value of
  537.      `sockbuf::so_dontroute' option. The default value of `opval' is -1.
  538.  
  539. `s.oobinline(opval)'
  540.      if `opval' is not -1, set the `sockbuf::so_oobinline' option value
  541.      to `opval'. In any case, return the old option value of
  542.      `sockbuf::so_oobinline' option. The default value of `opval' is -1.
  543.  
  544. `s.broadcast(opval)'
  545.      if `opval' is not -1, set the `sockbuf::so_broadcast' option value
  546.      to `opval'. In any case, return the old option value of
  547.      `sockbuf::so_broadcast' option. The default value of `opval' is -1.
  548.  
  549. `s.keepalive(opval)'
  550.      if `opval' is not -1, set the `sockbuf::so_keepalive' option value
  551.      to `opval'. In any case, return the old option value of
  552.      `sockbuf::so_keepalive' option. The default value of `opval' is -1.
  553.  
  554. `s.sendbufsz(opval)'
  555.      if `opval' is not -1, set the new send buffer size to `opval'. In
  556.      any case, return the old buffer size of the send buffer. The
  557.      default value of `opval' is -1.
  558.  
  559. `s.recvbufsz(opval)'
  560.      if `opval' is not -1, set the new recv buffer size to `opval'. In
  561.      any case, return the old buffer size of the recv buffer. The
  562.      default value of `opval' is -1.
  563.  
  564. `s.linger(tim)'
  565.      if `tim' is positive, set the linger time to tim seconds. If `tim'
  566.      is 0, set the linger off. In any case, return the old linger time
  567.      if it was set earlier. Otherwise return -1. The default value of
  568.      `tim' is -1.
  569.  
  570. 
  571. File: socket++.info,  Node: Timeouts,  Prev: Socket Options,  Up: sockbuf Class
  572.  
  573. Time Outs While Reading and Writing
  574. ===================================
  575.  
  576.    Time outs are very useful in handling data of unknown sizes and
  577. formats while reading and writing. For example, how does one
  578. communicate with a socket that sends chunks of data of unknown size and
  579. format? If only `sockbuf::read' is used without time out, it will block
  580. indefinitely. In such cases, time out facility is the only answer.
  581.  
  582.    The following idiom is recommended.
  583.  
  584.          int old_tmo = s.recvtimeout (2) // set time out (2 seconds here)
  585.          for (;;) { // read or write
  586.              char buf[256];
  587.              int rval = s.read (buf, 256);
  588.              if (rval == 0 || rval == EOF) break;
  589.              // process buf
  590.          }
  591.          s.recvtimeout (old_tmo); // reset time out
  592.  
  593.    In what follows,
  594.    - `s' is a `sockbuf' object
  595.  
  596.    - `wp' is waiting period in seconds
  597.  
  598. `s.recvtimeout(wp)'
  599.      sets the recv timeout to `wp' seconds. If `wp' is -1, it is a
  600.      block and if `wp' is 0, it is a poll.
  601.  
  602.      It affects all read functions. If the socket is not read ready
  603.      within `wp' seconds, the read call will return 0. It also affects
  604.      `sockbuf::underflow'. `sockbuf::underflow' will not set the
  605.      `_S_EOF_SEEN' flag if it is returning EOF because of timeout.
  606.  
  607.      `sockbuf::recvtimeout' returns the old recv timeout value.
  608.  
  609. `s.sendtimeout(wp)'
  610.      sets the send timeout to `wp' seconds. If `wp' is -1, it is a
  611.      block and if `wp' is 0, it is a poll.
  612.  
  613.      It affects all write functions. If the socket is not write ready
  614.      within `wp' seconds, the write call will return 0.
  615.  
  616.      `sockbuf::sendtimeout' returns the old send timeout value.
  617.  
  618. 
  619. File: socket++.info,  Node: sockAddr Class,  Next: sockinetbuf Class,  Prev: sockbuf Class,  Up: Top
  620.  
  621. sockAddr Class
  622. **************
  623.  
  624.    Class `sockAddr' is an abstract base class for all socket address
  625. classes. That is, domain specific socket address classes are all derived
  626. from `sockAddr' class.
  627.      *Note*: `sockAddr' is not spelled `sockaddr' in order to prevent
  628.      name clash with `struct sockaddr' declared in `<sys/socket.h>'.
  629.  
  630.    Non-abstract derived classes must have definitions for the following
  631. functions.
  632.  
  633. `sockAddr::operator void* ()'
  634.      should simply return `this'.
  635.  
  636. `sockAddr::size()'
  637.      should return `sizeof(*this)'. The return type is `int'.
  638.  
  639. `sockAddr::family()'
  640.      should return address family (domain name) of the socket address.
  641.      The return type is `int'
  642.  
  643. 
  644. File: socket++.info,  Node: sockinetbuf Class,  Next: sockinetaddr Class,  Prev: sockAddr Class,  Up: Top
  645.  
  646. sockinetbuf Class
  647. *****************
  648.  
  649.    `sockinetbuf' class is derived from `sockbuf' class and inherits
  650. most of the public functions of `sockbuf'. *Note sockbuf Class::, for
  651. more information on `sockbuf'. In addition, it provides methods for
  652. getting `sockinetaddr' of local and peer connections. *Note
  653. sockinetaddr Class::, for more information on `sockinetaddr'.
  654.  
  655. * Menu:
  656.  
  657. * Methods sockinetbuf::         Describes sockinetbuf member functions.
  658. * Datagram INET::               A pair of example programs demonstrating
  659.                                     datagram connection in inet domain.
  660. * Stream INET::                 A pair of example programs demonstrating
  661.                                     stream connection in inet domain.
  662.  
  663. 
  664. File: socket++.info,  Node: Methods sockinetbuf,  Next: Datagram INET,  Up: sockinetbuf Class
  665.  
  666. Methods
  667. =======
  668.  
  669.    In what follows,
  670.    - `ty' denotes the type of the socket connection and is of type
  671.      `sockbuf::type'
  672.  
  673.    - `proto' denotes the protocol and is of type int
  674.  
  675.    - `si' is a `sockbuf' object and is in INET domain
  676.  
  677. `sockinetbuf ins(ty, proto)'
  678.      Constructs a `sockinetbuf' object `ins' whose socket communication
  679.      type is `ty' and protocol is `proto'. `proto' defaults to 0.
  680.  
  681. `sockinetbuf ins(si)'
  682.      Constructs a `sockinetbuf' object `ins' which uses the same socket
  683.      as `si' uses.
  684.  
  685. `ins = si'
  686.      performs the same function as `sockbuf::operator='. *Note sockbuf
  687.      Class::, for more details.
  688.  
  689. `ins.open(ty, proto)'
  690.      create a new `sockinetbuf' whose type and protocol are `ty' and
  691.      `proto' respectively and assign it to `ins'.
  692.  
  693. `sockinetaddr sina = ins.localaddr()'
  694.      returns the local INET address of the `sockinetbuf' object `ins'.
  695.      The call will make sense only after a call to either
  696.      `sockbuf::bind' or `sockbuf::connect'.
  697.  
  698. `sockinetaddr sina = ins.peeraddr()'
  699.      returns the peer INET address of the `sockinetbuf' object `ins'.
  700.      The call will make sense only after a call to `sockbuf::connect'.
  701.  
  702. `const char* hn = ins.localhost()'
  703.      returns the local INET thostname of the `sockinetbuf' object
  704.      `ins'. The call will make sense only after a call to either
  705.      `sockbuf::bind' or `sockbuf::connect'.
  706.  
  707. `const char* hn = ins.peerhost()'
  708.      returns the peer INET thostname of the `sockinetbuf' object `ins'.
  709.      The call will make sense only after a call to `sockbuf::connect'.
  710.  
  711. `int pn = ins.localport()'
  712.      returns the local INET port number of the `sockinetbuf' object
  713.      `ins' in host byte order. The call will make sense only after a
  714.      call to either `sockbuf::bind' or `sockbuf::connect'.
  715.  
  716. `int pn = ins.peerport()'
  717.      returns the peer INET port number of the `sockinetbuf' object
  718.      `ins' in local host byte order. The call will make sense only
  719.      after a call to `sockbuf::connect'.
  720.  
  721. 
  722. File: socket++.info,  Node: Datagram INET,  Next: Stream INET,  Prev: Methods sockinetbuf,  Up: sockinetbuf Class
  723.  
  724. INET Datagram Sockets
  725. =====================
  726.  
  727.    The following two programs illustrates how to use `sockinetbuf' class
  728. for datagram connection in INET domain. `tdinread.cc' also shows how to
  729. use `isockstream' class and `tdinwrite.cc' shows how to use
  730. `osockstream' class.
  731.  
  732. tdinread.cc
  733. -----------
  734.  
  735.      // reads data sent by tdinwrite.cc
  736.      #include <sockinet.h>
  737.      
  738.      main(int ac, char** av)
  739.      {
  740.              sockinetbuf  so (sockbuf::sock_dgram);
  741.              sockinetaddr sina;
  742.      
  743.              so.bind(sina);
  744.      
  745.              cout << "localhost = " << so.localhost() << endl
  746.                   << "localport = " << so.localport() << endl;
  747.      
  748.              isockstream  is(so);
  749.              char         buf[256];
  750.              int          n;
  751.      
  752.              is >> n;
  753.              cout << av[0] << ": ";
  754.              while(n--) {
  755.                      is >> buf;
  756.                      cout << buf << ' ';
  757.              }
  758.              cout << endl;
  759.      }
  760.  
  761. tdinwrite.cc
  762. ------------
  763.  
  764.      // sends data to tdinread.cc
  765.      #include <sockinetbuf.h>
  766.      
  767.      extern "C" int        atoi(const char*);
  768.      
  769.      main(int ac, char** av)
  770.      {
  771.              if (ac < 3) {
  772.                      cerr << "USAGE: " << av[0] << " thostname port-number "
  773.                           << "data ... " << endl;
  774.                      return 1;
  775.              }
  776.      
  777.              sockinetbuf     so(sockbuf::sock_dgram);
  778.              sockinetaddr    sina(av[1], atoi(av[2]));
  779.      
  780.              so.connect(sina);
  781.      
  782.              cout << "local: " << so.localport() << ' '
  783.                                << so.localhost() << endl
  784.                   << "peer:  " << so.peerport() << ' '
  785.                                << so.peerhost() << endl;
  786.              osockstream os(so);
  787.              os << ac-3; av += 3;
  788.              while(*av) os << *av++ << ' ';
  789.              os << endl;
  790.      }
  791.  
  792. 
  793. File: socket++.info,  Node: Stream INET,  Prev: Datagram INET,  Up: sockinetbuf Class
  794.  
  795. INET Stream Sockets
  796. ===================
  797.  
  798.    The following two programs illustrates the use of `sockinetbuf' class
  799. for stream connection in INET domain. It also shows how to use
  800. `iosockstream' class.
  801.  
  802. tsinread.cc
  803. -----------
  804.  
  805.      // receives strings from tsinwrite.cc and sends the strlen
  806.      // of each string back to tsinwrite.cc
  807.      #include        <sockinet.h>
  808.      
  809.      main()
  810.      {
  811.              sockinetaddr    addr;
  812.              sockinetbuf     si(sockbuf::sock_stream);
  813.              si.bind(addr);
  814.      
  815.              cout << si.localhost() << ' ' << si.localport() << endl;
  816.              si.listen();
  817.              sockinetbuf sin = si.accept();
  818.      
  819.              char          buf[1024];
  820.              iosockstream  s(sin);
  821.      
  822.              while (s >> buf) {
  823.                      cout << buf << ' ';
  824.                      s << ::strlen(buf) << endl;
  825.              }
  826.              cout << endl;
  827.      }
  828.  
  829. tsinwrite.cc
  830. ------------
  831.  
  832.      // sends strings to tsinread.cc and gets back their length
  833.      // usage: tsinread hostname portno
  834.      //        see the output of tsinread for what hostname and portno to use
  835.      
  836.      #include        <sockinet.h>
  837.      
  838.      extern "C" int atoi(const char*);
  839.      
  840.      main(int ac, char** av)
  841.      {
  842.              sockinetaddr    addr(av[1], atoi(av[2]) );
  843.              sockinetbuf     si(sockbuf::sock_stream);
  844.      
  845.              si.connect(addr);
  846.              iosockstream s(si);
  847.              s << "Hello! This is a test\n";
  848.      
  849.              // terminate the while loop in tsinread.cc
  850.              si.shutdown(sockbuf::shut_write);
  851.      
  852.              int len;
  853.              while (s >> len) cout << len << ' ';
  854.              cout << endl;
  855.      }
  856.  
  857. 
  858. File: socket++.info,  Node: sockinetaddr Class,  Next: sockunixbuf Class,  Prev: sockinetbuf Class,  Up: Top
  859.  
  860. sockinetaddr Class
  861. ******************
  862.  
  863.    Class `sockinetaddr' is derived from `sockAddr' declared in
  864. `<sockstream.h>' and from `sockaddr_in' declared in `<netinet/in.h>'.
  865. Always use a `sockinetaddr' object for an address with INET domain of
  866. sockets. *Note Connection Establishment::.
  867.  
  868.    In what follows,
  869.    - `adr' denotes an INET address in host byte order and is of type
  870.      unsigned long
  871.  
  872.    - `serv' denotes a service like "nntp" and is of type char*
  873.  
  874.    - `proto' denotes a protocol like "tcp" and is of type char*
  875.  
  876.    - `thostname' is of type char* and denotes the name of a host like
  877.      `"kelvin.acc.virginia.edu"' or `"128.143.24.31"'.
  878.  
  879.    - `portno' denotes a port in host byte order and is of type int
  880.  
  881. `sockinetaddr sina'
  882.      Constructs a `sockinetaddr' object `sina' with default address
  883.      INADDR_ANY and default port number 0.
  884.  
  885. `sockinetaddr sina(adr, portno)'
  886.      Constructs a `sockinetaddr' object `sina' setting inet address to
  887.      `adr' and the port number to `portno'. `portno' defaults to 0.
  888.  
  889. `sockinetaddr sina(adr, serv, proto)'
  890.      Constructs a `sockinetaddr' object `sina' setting inet address to
  891.      `adr' and the port number corresponding to the service `serv' and
  892.      the protocol `proto'. The protocol defaults to "tcp".
  893.  
  894. `sockinetaddr sina(thostname, portno)'
  895.      Constructs a `sockinetaddr' object `sina' setting inet address to
  896.      the address of `thostname' and the port number to `portno'.
  897.      `portno' defaults to 0.
  898.  
  899. `sockinetaddr sina(thostname, serv, proto)'
  900.      Constructs a `sockinetaddr' object `sina' setting inet address to
  901.      the address of `thostname' and the port number corresponding to
  902.      the service `serv' and the protocol `proto'. The protocol defaults
  903.      to "tcp".
  904.  
  905. `void* a = sina'
  906.      returns the address of the `sockaddr_in' part of `sockinetaddr'
  907.      object `sina' as void*.
  908.  
  909. `int sz = sina.size()'
  910.      returns the sizeof `sockaddr_in' part of `sockinetaddr' object
  911.      `sina'.
  912.  
  913. `int af = sina.family()'
  914.      returns `sockinetbuf::af_inet' if all is well.
  915.  
  916. `int pn = sina.getport()'
  917.      returns the port number of the `sockinetaddr' object `sina' in
  918.      host byte order.
  919.  
  920. `const char* hn = getthostname()'
  921.      returns the host name of the `sockinetaddr' object `sina'.
  922.  
  923. 
  924. File: socket++.info,  Node: sockunixbuf Class,  Next: sockunixaddr Class,  Prev: sockinetaddr Class,  Up: Top
  925.  
  926. sockunixbuf Class
  927. *****************
  928.  
  929.    `sockunixbuf' class is derived from `sockbuf' class declared in
  930. `<sockstream.h>' and hence, inherits most of the public member
  931. functions of `sockbuf'. *Note sockbuf Class::, for more information on
  932. `sockbuf'.
  933.  
  934. * Menu:
  935.  
  936. * Methods sockunixbuf::         Describes sockunixbuf member functions
  937. * Datagram UNIX::               A pair of example programs demonstrating
  938.                                     datagram connection in UNIX domain
  939. * Stream UNIX::                 A pair of example programs demonstrating
  940.                                     stream connection in UNIX domain
  941.  
  942. 
  943. File: socket++.info,  Node: Methods sockunixbuf,  Next: Datagram UNIX,  Up: sockunixbuf Class
  944.  
  945. Methods
  946. =======
  947.  
  948.    In what follows,
  949.    - `ty' denotes the socket type and is of type `sockbuf::type'
  950.  
  951.    - `proto' denotes the protocol number and is of type int
  952.  
  953.    - `su' is a `sockbuf' and must be in UNIX domain
  954.  
  955. `sockunixbuf uns(ty, proto)'
  956.      Constructs a `sockunixbuf' object `uns' with `ty' as its type and
  957.      `proto' as its protocol number. `proto' defaults to 0.
  958.  
  959. `sockunixbuf uns = su'
  960.      Constructs a `sockunixbuf' object `uns' which uses the same socket
  961.      as is used by `su'.
  962.  
  963. `uns = su'
  964.      `sockunixbuf' object `uns' closes its current socket if no other
  965.      `sockbuf' is referring to it and uses the socket that `sockbuf'
  966.      object `su' is using.
  967.  
  968. `uns.open(ty, proto)'
  969.      create a `sockunixbuf' object with `ty' as its type and `proto' as
  970.      its protocol and assign the `sockunixbuf' object so created to
  971.      `*this'. It returns `this'. `proto' defaults to 0.
  972.  
  973. 
  974. File: socket++.info,  Node: Datagram UNIX,  Next: Stream UNIX,  Prev: Methods sockunixbuf,  Up: sockunixbuf Class
  975.  
  976. UNIX Datagram Sockets
  977. =====================
  978.  
  979.    The following two programs illustrates how to use `sockunixbuf' class
  980. for datagram connection in UNIX domain. `tdunread.cc' also shows how to
  981. use `isockstream' class and `tdunwrite.cc' shows how to use
  982. `osockstream' class.
  983.  
  984. tdunread.cc
  985. -----------
  986.  
  987.      // reads data sent by tdunwrite.cc
  988.      #include <sockunix.h>
  989.      
  990.      extern "C" {
  991.              int  chmod(const char* path, int mode);
  992.              void perror(const char*);
  993.              int  unlink(const char* path);
  994.      }
  995.      
  996.      main(int ac, char** av)
  997.      {
  998.              if (ac != 2) {
  999.                      cerr << "USAGE: " << av[0] << " socket_path_name\n";
  1000.                      return 1;
  1001.              }
  1002.      
  1003.              sockunixbuf  sunb(sockbuf::sock_dgram);
  1004.              sockunixaddr suna(av[1]);
  1005.      
  1006.              sunb.bind(suna);
  1007.              cout << "Socket name = " << av[1] << endl;
  1008.      
  1009.              if (chmod(av[1], 0777) == -1) {
  1010.                      perror("chmod");
  1011.                      return 1;
  1012.              }
  1013.      
  1014.              isockstream isun(sunb);
  1015.      
  1016.              char buf[1024];
  1017.              int i;
  1018.              isun >> i;
  1019.              cout << av[0] << ": " << i << " strings: ";
  1020.              while (i--) {
  1021.                      isun >> buf;
  1022.                      cout  << buf << ' ';
  1023.              }
  1024.              cout << endl;
  1025.      
  1026.              unlink(av[1]);
  1027.      }
  1028.  
  1029. tdunwrite.cc
  1030. ------------
  1031.  
  1032.      // sends data to tdunread.cc
  1033.      #include <sockunix.h>
  1034.      
  1035.      main(int ac, char** av)
  1036.      {
  1037.              if (ac < 2) {
  1038.                      cerr << "USAGE: " << av[0]
  1039.                           << " socket_path_name data...\n";
  1040.                      return 1;
  1041.              }
  1042.      
  1043.              sockunixbuf  sunb(sockbuf::sock_dgram);
  1044.              sockunixaddr suna(av[1]);
  1045.      
  1046.              sunb.connect(suna);
  1047.              osockstream        osun(sunb);
  1048.              osun << ac << ' ';
  1049.              for (int i=0; av[i]; i++) osun << av[i] << ' ';
  1050.              osun << endl;
  1051.      
  1052.      }
  1053.  
  1054. 
  1055. File: socket++.info,  Node: Stream UNIX,  Prev: Datagram UNIX,  Up: sockunixbuf Class
  1056.  
  1057. UNIX Stream Sockets
  1058. ===================
  1059.  
  1060.    The following two programs illustrates how to use `sockunixbuf' class
  1061. for stream connection in UNIX domain. It also shows how to use
  1062. `iosockstream' class.
  1063.  
  1064. tsunread.cc
  1065. -----------
  1066.  
  1067.      // exchanges char strings with tsunwrite.cc
  1068.      #include <sockunix.h>
  1069.      
  1070.      extern "C" {
  1071.              int  chmod(const char* path, int mode);
  1072.              void perror(const char*);
  1073.              int  unlink(const char* path);
  1074.      }
  1075.      
  1076.      main(int ac, char** av)
  1077.      {
  1078.              if (ac != 2) {
  1079.                      cerr << "USAGE: " << av[0] << " socket_path_name\n";
  1080.                      return 1;
  1081.              }
  1082.      
  1083.              sockunixbuf  su(sockbuf::sock_stream);
  1084.              sockunixaddr suna(av[1]);
  1085.      
  1086.              su.bind(suna);
  1087.              cout << "Socket name = " << av[1] << endl;
  1088.      
  1089.              if (chmod(av[1], 0777) == -1) {
  1090.                      perror("chmod");
  1091.                      return 1;
  1092.              }
  1093.      
  1094.              su.listen(3);
  1095.              sockunixbuf so = su.accept();
  1096.      
  1097.              iosockstream ioput(so);
  1098.              char         buf[1024];
  1099.      
  1100.              ioput << av[0] << ' ' << av[1] << endl;
  1101.              while ( ioput >> buf ) cout << av[0] << ": " << buf << endl;
  1102.              unlink(av[1]);
  1103.      }
  1104.  
  1105. tsunwrite.cc
  1106. ------------
  1107.  
  1108.      // exchanges char strings with tsunread.cc
  1109.      #include <sockunix.h>
  1110.      
  1111.      main(int ac, char** av)
  1112.      {
  1113.              if (ac < 2) {
  1114.                      cerr << "USAGE: " << av[0]
  1115.                           << " socket_path_name data...\n";
  1116.                      return 1;
  1117.              }
  1118.      
  1119.              sockunixbuf  su(sockbuf::sock_stream);
  1120.              sockunixaddr suna(av[1]);
  1121.      
  1122.              su.connect(suna);
  1123.              iosockstream oput(su);
  1124.              char buf[128];
  1125.      
  1126.              oput >> buf;
  1127.              cout << buf << ' ';
  1128.              oput >> buf;
  1129.              cout << buf << endl;
  1130.      
  1131.              while (*av) oput << *av++ << ' ';
  1132.              oput << endl;
  1133.      }
  1134.  
  1135. 
  1136. File: socket++.info,  Node: sockunixaddr Class,  Next: sockstream Classes,  Prev: sockunixbuf Class,  Up: Top
  1137.  
  1138. sockunixaddr Class
  1139. ******************
  1140.  
  1141.    Class `sockunixaddr' is derived from class `sockAddr' declared in
  1142. `<sockstream.h>' and from struct `sockaddr_un' declared in
  1143. `<sys/un.h>'. Always use `sockunixaddr' objects for addresses with UNIX
  1144. domain of sockets. *Note Connection Establishment::.
  1145.  
  1146.    In what follows,
  1147.    - `path' is the UNIX path name like "/tmp/unix_socket"
  1148.  
  1149. `sockunixaddr suna(path)'
  1150.      Constructs a `sockunixaddr' object `suna' with `path' as the UNIX
  1151.      path name.
  1152.  
  1153. `void* a = suna'
  1154.      returns the address of the `sockaddr_un' part of `sockunixaddr'
  1155.      object `suna' as void*.
  1156.  
  1157. `int sz = suna.size()'
  1158.      returns the sizeof `sockaddr_un' part of `sockunixaddr' object
  1159.      `suna'.
  1160.  
  1161. `int af = suna.family()'
  1162.      returns `sockunixbuf::af_unix' if all is well.
  1163.  
  1164. 
  1165. File: socket++.info,  Node: sockstream Classes,  Next: pipestream Classes,  Prev: sockunixaddr Class,  Up: Top
  1166.  
  1167. sockstream Classes
  1168. ******************
  1169.  
  1170.    sockstream classes are designed in such a way that they provide the
  1171. same interface as their stream counterparts do. We have `isockstream'
  1172. derived from `istream' and `osockstream' derived from `ostream'. We
  1173. also have `iosockstream' which is derived from `iostream'.
  1174.  
  1175.    Each domain also has its own set of `stream' classes. For example,
  1176. `unix' domain has `isockunix', `osockunix', and `iosockunix' derived
  1177. from `isockstream', `osockstream', and `iosockstream' respectively.
  1178. Similarly, `inet' domain has `isockinet', `osockinet', and `iosockinet'.
  1179.  
  1180. * Menu:
  1181.  
  1182. * iosockstream::             Generic IOStream classes for sockbuf
  1183.                                    buffers.
  1184. * iosockinet::               IOStream classes for INET domain of
  1185.                                    sockets.
  1186. * iosockunix::               IOStream classes for UNIX domain of
  1187.                                    sockets.
  1188.  
  1189. 
  1190. File: socket++.info,  Node: iosockstream,  Next: iosockinet,  Up: sockstream Classes
  1191.  
  1192. iosockstreams
  1193. =============
  1194.  
  1195. isockstream Class
  1196. -----------------
  1197.  
  1198.    Since `isockstream' is publicly derived from `istream', most of the
  1199. public functions of `istream' are also available in `isockstream'.
  1200.  
  1201.    `isockstream' redefines `rdbuf()' defined in its virtual base class
  1202. `ios'. Since, `ios::rdbuf()' is not virtual, care must be taken to call
  1203. the correct `rdbuf()' through a reference or a pointer to an object of
  1204. class `isockstream'.
  1205.  
  1206.    In what follows,
  1207.    - `sb' is a `sockbuf' object
  1208.  
  1209.    - `sbp' is a pointer to a `sockbuf' object
  1210.  
  1211. `isockstream is(sb)'
  1212.      Constructs an `isockstream' object `is' with `sb' as its `sockbuf'.
  1213.  
  1214. `isockstream is(sbp)'
  1215.      Constructs an `isockstream' object `is' with `*sbp' as its
  1216.      `sockbuf'.
  1217.  
  1218. `sbp = is.rdbuf()'
  1219.      returns a pointer to the `sockbuf' of the `isockstream' object
  1220.      `is'.
  1221.  
  1222. `isockstream::operator -> ()'
  1223.      returns a pointer to the `isockstream''s `sockbuf' so that the
  1224.      user can use `isockstream' object as a `sockbuf' object.
  1225.  
  1226.               is->connect (sa); // same as is.rdbuf()->connect (sa);
  1227.  
  1228. osockstream Class
  1229. -----------------
  1230.  
  1231.    Since `osockstream' is publicly derived from `ostream', most of the
  1232. public functions of `ostream' are also available in `osockstream'.
  1233.  
  1234.    `osockstream' redefines `rdbuf()' defined in its virtual base class
  1235. `ios'. Since, `ios::rdbuf()' is not virtual, care must be taken to call
  1236. the correct `rdbuf()' through a reference or a pointer to an object of
  1237. class `osockstream'.
  1238.  
  1239.    In what follows,
  1240.    - `sb' is a `sockbuf' object
  1241.  
  1242.    - `sbp' is a pointer to a `sockbuf' object
  1243.  
  1244. `osockstream os(sb)'
  1245.      Constructs an `osockstream' object `os' with `sb' as its `sockbuf'.
  1246.  
  1247. `osockstream os(sbp)'
  1248.      Constructs an `osockstream' object `os' with `*sbp' as its
  1249.      `sockbuf'.
  1250.  
  1251. `sbp = os.rdbuf()'
  1252.      returns a pointer to the `sockbuf' of the `osockstream' object
  1253.      `os'.
  1254.  
  1255. `osockstream::operator -> ()'
  1256.      returns a pointer to the `osockstream''s `sockbuf' so that the
  1257.      user can use `osockstream' object as a `sockbuf' object.
  1258.  
  1259.               os->connect (sa); // same as os.rdbuf()->connect (sa);
  1260.  
  1261. iosockstream Class
  1262. ------------------
  1263.  
  1264.    Since `iosockstream' is publicly derived from `ostream', most of the
  1265. public functions of `ostream' are also available in `iosockstream'.
  1266.  
  1267.    `iosockstream' redefines `rdbuf()' defined in its virtual base class
  1268. `ios'. Since, `ios::rdbuf()' is not virtual, care must be taken to call
  1269. the correct `rdbuf()' through a reference or a pointer to an object of
  1270. class `iosockstream'.
  1271.  
  1272.    In what follows,
  1273.    - `sb' is a `sockbuf' object
  1274.  
  1275.    - `sbp' is a pointer to a `sockbuf' object
  1276.  
  1277. `iosockstream io(sb)'
  1278.      Constructs an `iosockstream' object `io' with `sb' as its
  1279.      `sockbuf'.
  1280.  
  1281. `iosockstream io(sbp)'
  1282.      Constructs an `iosockstream' object `io' with `*sbp' as its
  1283.      `sockbuf'.
  1284.  
  1285. `sbp = io.rdbuf()'
  1286.      returns a pointer to the `sockbuf' of the `iosockstream' object
  1287.      `io'.
  1288.  
  1289. `iosockstream::operator -> ()'
  1290.      returns a pointer to the `iosockstream''s `sockbuf' so that the
  1291.      user can use `iosockstream' object as a `sockbuf' object.
  1292.  
  1293.               io->connect (sa); // same as io.rdbuf()->connect (sa);
  1294.  
  1295. 
  1296. File: socket++.info,  Node: iosockinet,  Next: iosockunix,  Prev: iosockstream,  Up: sockstream Classes
  1297.  
  1298. iosockinet Stream Classes
  1299. =========================
  1300.  
  1301.    We discus only `isockinet' class here. `osockinet' and `iosockinet'
  1302. are similar and are left out. However, they are covered in the examples
  1303. that follow.
  1304.  
  1305. isockinet
  1306. ---------
  1307.  
  1308.    `isockinet' is used to handle interprocess communication in INET
  1309. domain. It is derived from `isockstream' class and it uses a
  1310. `sockinetbuf' as its stream buffer. *Note iosockstream::, for more
  1311. details on `isockstream'. *Note sockinetbuf Class::, for information on
  1312. `sockinetbuf'.
  1313.  
  1314.    In what follows,
  1315.    - `ty' is a `sockbuf::type' and must be one of
  1316.      `sockbuf::sock_stream', `sockbuf::sock_dgram',
  1317.      `sockbuf::sock_raw', `sockbuf::sock_rdm', and
  1318.      `sockbuf::sock_seqpacket'
  1319.  
  1320.    - `proto' denotes the protocol number and is of type int
  1321.  
  1322.    - `sb' is a `sockbuf' object and must be in INET domain
  1323.  
  1324.    - `sinp' is a pointer to an object of `sockinetbuf'
  1325.  
  1326. `isockinet is (ty, proto)'
  1327.      constructs an `isockinet' object `is' whose `sockinetbuf' buffer
  1328.      is of the type `ty' and has the protocol number `proto'. The
  1329.      default protocol number is 0.
  1330.  
  1331. `isockinet is (sb)'
  1332.      constructs a `isockinet' object `is' whose `sockinetbuf' is `sb'.
  1333.      `sb' must be in INET domain.
  1334.  
  1335. `isockinet is (sinp)'
  1336.      constructs a `isockinet' object `is' whose `sockinetbuf' is `sinp'.
  1337.  
  1338. `sinp = is.rdbuf ()'
  1339.      returns a pointer to the `sockinetbuf' of `isockinet' object `is'.
  1340.  
  1341. `isockinet::operator ->'
  1342.      returns `sockinetbuf' of `sockinet' so that the `sockinet' object
  1343.      acts as a smart pointer to `sockinetbuf'.
  1344.  
  1345.                   is->localhost (); // same as is.rdbuf ()->localhost ();
  1346.  
  1347. iosockinet examples
  1348. -------------------
  1349.  
  1350.    The first pair of examples demonstrates datagram socket connections
  1351. in the INET domain. First, `tdinread' prints its local host and local
  1352. port on stdout and waits for input in the connection. `tdinwrite' is
  1353. started with the local host and local port of `tdinread' as arguments.
  1354. It sends the string "How do ye do!" to `tdinread' which in turn reads
  1355. the string and prints on its stdout.
  1356.  
  1357.      // tdinread.cc
  1358.      #include <sockinet.h>
  1359.      
  1360.      main ()
  1361.      {
  1362.          char buf[256];
  1363.          isockinet is (sockbuf::sock_dgram);
  1364.      
  1365.          sockinetaddr sina;
  1366.          is->bind (sina);
  1367.      
  1368.          cout << is->localhost() << ' ' << is->localport() << endl;
  1369.      
  1370.          is.getline (buf);
  1371.          cout << buf << endl;
  1372.      }
  1373.  
  1374.      // tdinwrite.cc--tdinwrite hostname portno
  1375.      #include <sockinet.h>
  1376.      
  1377.      extern "C" int atoi (const char*);
  1378.      
  1379.      main (int ac, char** av)
  1380.      {
  1381.          osockinet os (sockbuf::sock_dgram);
  1382.          sockinetaddr sina (av[1], atoi(av[2]));
  1383.          os->connect (sina);
  1384.          os << "How do ye do!\n";
  1385.      }
  1386.  
  1387.    The next example communicates with an nntp server through a
  1388. `sockbuf::sock_stream' socket connection in INET domain. After
  1389. establishing a connection to the nntp server, it sends a "HELP" command
  1390. and gets back the HELP message before sending the "QUIT" command.
  1391.  
  1392.      // tnntp.cc
  1393.      #include <sockinet.h>
  1394.      
  1395.      main ()
  1396.      {
  1397.          char  buf[1024];
  1398.          iosockinet io (sockbuf::sock_stream);
  1399.          sockinetaddr sina ("murdoch.acc.virginia.edu", "nntp", "tcp");
  1400.          io->connect (sina);
  1401.          io.getline (buf, 1024); cout << buf << endl;
  1402.          io << "HELP\r\n";
  1403.          io.getline (buf, 1024); cout << buf << endl;
  1404.          while (io.getline (buf, 1024))
  1405.              if (buf[0] == '.' && buf[1] == '\r') break;
  1406.              else if (buf[0] == '.' && buf[1] == '.') cout << buf+1 << endl;
  1407.              else cout << buf << endl;
  1408.          io << "QUIT\r\n";
  1409.          io.getline (buf, 1024); cout << buf << endl;
  1410.      }
  1411.  
  1412.